Skip to content

H12: <Screen app> draws its app on a Blitz document of its own - #161

Open
shinyobjectz wants to merge 6 commits into
mainfrom
appscreen
Open

shinyobjectz wants to merge 6 commits into
mainfrom
appscreen

Conversation

@shinyobjectz

@shinyobjectz shinyobjectz commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

<Screen app="kit.tsx"> now draws its app. Until this PR, raea refused it ("isn't drawn yet: app screens move to raea-runtime-js roots of their own (ts-native P27)"), so a composition that put a React UI on a 3D screen got a blank panel. This change runs the module's component on @raea/ui's react-dom in a Blitz document of its own and copies its picture onto the screen the way a nested composition's picture is copied.

What changed

  • New crate runtime/appscreen (raea-runtime-appscreen). An AppScreen opens the module (its prebuilt bundle if there is one, otherwise it bundles it with its CSS and its folder's Tailwind). It mounts the component with { width, height } on a Blitz page and steps it once per frame. It turns the routed pointer, keys and wheel into window events. Routed holds what reached the app screens in a frame and round-trips it through the input log.
  • app::bundle takes the props its default export is mounted with (app::WINDOW for an app in its own window, app::SCREEN for an app screen's { width, height }). The callers in apps/targets and the rune host's tests pass WINDOW, which is what they got before.
  • A held JS clock (runtime/jsengine): at_clock(ms, f) makes performance.now and timers read the frame's time during a step. A render therefore repeats frame for frame.
  • runtime/page: screen.rs opens, steps and retires app screens (step_all, retire) and hands their textures and pictures to the 3D. The refusal line is gone.
  • Play and render. Live play logs what reached each app screen per frame (apps in the input log). raea render --input gives the same input back through APP_LOG, so the render draws what was played. While an app screen has the keys, the game doesn't get them (runtime/live).
  • Export. export-game writes X.tsx.surface.js and .surface.css beside each app module, so the player no longer needs a separate feature for app screens.
  • Docs. The H12 scenario and P27c's updated line are in the private spec (docs/blitz-bevy.feature, docs/ts-native.feature) and already pushed there. <Screen app>'s doc, the manual's 3D reference and the motion/apps.md guide are updated, including a new "Not yet" list.

Measured

  • The new bench case is sdk/raea/bench/bevy/appscreen: a button in an app on a flat screen, clicked through the 3D, with a timer bar. check.sh passes 9 of 9 on exact colours. The checks: drawn, hover ring, pressed-not-released, clicked from the release on, ring gone after the pointer leaves, a timer bar on the frame clock, and apps entries kept in the log.
  • The new bench/render-play/appscreen row scores 1.000000 SSIM between play and render at frames 6, 12, 18 and 27. The whole render-play bench passes 14 of 14.
  • Rendering the same log with its apps entries stripped shows the button unclicked (SSIM 0.9909 against the play). The click really travels through the log.
  • Unit tests pass for raea-runtime-appscreen, raea-runtime-jsengine, raea-runtime-page, raea-runtime-live, raea-runtime-bundle-lib and raea-app-targets; the rune host's tests compile.
  • L1 (tools/agents/check --land --lane appscreen) passes every step, dupes at 292 exact and 59 near.

Merge with raea-skills #89

The skills submodule is pinned to shinyobjectz/raea-skills#89 (80067cc), which carries the same motion/apps.md guide. Merge #89 together with this PR, then repin skills to #89's merge commit.

Not tested

  • The export-game path end to end: the bundles are written, but an exported player drawing an app screen hasn't been run.

Not yet (in the guide)

  • Date in an app screen reads the wall clock, so a render shows another time than its play. Timers and performance.now follow the frame.
  • A drag that leaves an app screen ends at its edge. Double click isn't supported.
  • The page host's desktop calls (clipboard, links, notifications) don't work in an app screen.

🤖 Generated with Claude Code

raea-runtime-jsengine at_clock(ms, f) runs f with this thread's JS clock (the timers' now and performance.now) held at ms, so a root stepped on a composition's frames sees the same time in a render and its play. raea-runtime-bundle-lib app::bundle_screen bundles a module as an app is, its default export given {width: innerWidth, height: innerHeight}: an app screen's, one bundle for a screen of any size. bundle_surface (real react-dom/client into #root, the old Blitz surface's entry) is gone; nothing calls it.
raea-runtime-appscreen opens each app screen's module on a BlitzPage of its own at the screen's size, on the shared device, with the CSS its modules import and Tailwind's for its folder (or an exported game's prebuilt X.tsx.surface.js and .surface.css). It is stepped once a frame: the input route() gave it as Blitz's pointer, wheel and key events, then one update that runs its JS on the frame's clock, and paints; the draw's later updates while faces load only paint. runtime/page's sync steps every app screen (screen.rs step_all, at at_frame's frame in a render and set_app_frame's in live play) instead of saying it isn't drawn, and its picture goes with the nested screens' (screen_textures, frame_all) to Engine::copy_screen or set_screen_picture.
…n; exported games bundle app screens as apps

Live play routes the pointer, wheel and keys to an app screen through the 3D (screen.rs route); its input log now keeps what reached the app screens each frame under `apps` (BevyPage::app_input) and leaves the keys they took out of the page's, and raea render --input gives the app screens the same (screen.rs APP_LOG), so the render draws what was played. Live play sets the app screens' frame each step. export-game writes each app screen's X.tsx.surface.js and .surface.css with the new bundle, and its check for the old surface runtime (a marker no player has had since Blitz left) is gone: every player draws app screens on its own Blitz page.
…ve P27c points at it); the appscreen bench (sdk/raea/bench/bevy/appscreen: a button clicked through the 3D, its own timer on the frame's clock; check.sh 9 PASS) and its bench/render-play row (1.000000 at frames 6, 12, 18 and 27; the bench 14 of 14); the apps guide, <Screen app>'s doc and the manual's reference; skills pin: raea-skills #89 (80067cc), motion/apps.md the same guide
… in raea-runtime-appscreen, and an app screen's texture handed over as bevy's; live play's needs_react in its own file (raea-runtime-page under 2000 lines, runtime/live/src/lib.rs under 500, no new duplicate groups)
…WINDOW, SCREEN) in place of two one-line forwarders; the app screens' log read through screen::logged (no new duplicate groups: 292 exact, 59 near)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant